Programming With QuickTime VR
| Previous | Chapter Contents | Chapter Top | Next |
The QuickTime VR Manager provides functions that you can use to manage the hot spots of a node.
You can use the QTVRPtToHotSpotID function to get the ID of the hot spot, if any, that lies beneath a point.
OSErr QTVRPtToHotSpotID (QTVRInstance qtvr, Pointpt, UInt32*hotSpotID);
The QTVRPtToHotSpotID function returns, in the long integer pointed to by the hotSpotID parameter, the ID of the hot spot in the QuickTime VR movie specified by the qtvr parameter that lies directly under the point specified by the pt parameter. If no hot spot lies under that point, the long integer is set to 0.
You can use the QTVRGetHotSpotType function to get the type of a hot spot.
OSErr QTVRGetHotSpotType (
QTVRInstance qtvr,
UInt32 hotSpotID,
OSType *hotSpotType);
The QTVRGetHotSpotType function gets the type of a hot spot whose ID you specify. In combination with the kQTVRGetHotSpotTypeSelector intercept selector, this allows an application to change a hot spot's type dynamically.
For example, an application can take an existing movie and cause VR to display the cursors for a type of hotspot different from the one the movie was originally authored with. In combination with intercepting kQTVRTriggerHotSpotSelector , this would allow an Internet plugin to override undefined or link hotspots in movies to make them appear and act as though they are URL links instead. If kQTVRTriggerHotSpotSelector is not intercepted, VR will attempt to act on the hotspot in the normal way; by storing both link and URL data in a file, the exact behavior can be determined at runtime by an application to allow linking to either another node locally or a remote URL link, depending on system configuration or other arbitrary considerations.
You can use the QTVRTriggerHotSpot function to trigger a hot spot.
OSErr QTVRTriggerHotSpot (
QTVRInstance qtvr,
UInt32hotSpotID,
QTAtomContainernodeInfo,
QTAtomselectedAtom);
One way you can use the QTVRTriggerHotSpot function is to execute any hot spot without the user's having clicked the hot spot. Usually, you need only specify the qtvr instance and the hot spot ID. You can pass zero for the nodeInfo and selectedAtom parameters.
The more common use of the QTVRTriggerHotSpot function is not in calling it directly, but in setting up an intercept procedure on it. The QTVRTriggerHotSpot function is called internally by the QuickTime VR Manager whenever a user clicks a hot spot. You can intercept calls to trigger your custom hot spots, which allows you to perform any custom actions you desire.
When the QTVRTriggerHotSpot function is called internally (and then intercepted by your intercept procedure), the nodeInfo and selectedAtom parameters have been properly set by the QuickTime VR Manager and are available for your use. For undefined hot spots that do not have an associated hot spot atom in the node info atom container, the selectedAtom parameter will be set to zero.
You can call QTVRTriggerHotSpot even on hot spots that are currently disabled.
Use QTVRInstallInterceptProc to install an intercept procedure. Listing 4-2 in Chapter 4, "QuickTime VR Atom Containers," shows an example of using an intercept procedure on the QTVRTriggerHotSpot function.
You can use the QTVREnableHotSpot function to enable or disable one or more hot spots.
OSErr QTVREnableHotSpot (
QTVRInstance qtvr,
UInt32enableFlag,
UInt32hotSpotValue,
Booleanenable);
The QTVREnableHotSpot function either enables or disables the hot spot or spots specified by the enableFlag and hotSpotValue parameters, according to the value of the enable parameter. The hot spots are always selected from among the hot spots in the current node of the QuickTime VR movie specified by the qtvr parameter.
Normally, all hot spots in a node are enabled (that is, the cursor automatically changes shape when it is moved over a hot spot, and the QTVRTriggerHotSpot function is called internally when the user clicks a hot spot). When a hot spot is disabled, QuickTime VR behaves as if the hot spot were not present.
You can use the QTVRSetMouseOverHotSpotProc function to install or remove a mouse over hot spot procedure.
OSErr
QTVRSetMouseOverHotSpotProc (
QTVRInstance qtvr,
QTVRMouseOverHotSpotUPP mouseOverHotSpotProc,
SInt32 refCon,
UInt32 flags);
The QTVRSetMouseOverHotSpotProc function installs the routine specified by the mouseOverHotSpotProc parameter as a mouse over hot spot procedure for the QuickTime VR movie specified by the qtvr parameter. Subsequent user actions (such as moving the cursor over an enabled hot spot in that movie) cause the callback routine to be executed. The reference constant specified by the refCon parameter is passed unchanged to your callback routine.
To remove a previously installed callback routine, set mouseOverHotSpotProc to nil .
Your mouse over hot spot procedure is called only for enabled hot spots.
You can use the QTVRGetVisibleHotSpots function to get a list of the currently visible hot spots in a QuickTime VR movie.
UInt32 QTVRGetVisibleHotSpots (QTVRInstance qtvr, Handle hotSpots);
The QTVRGetVisibleHotSpots function returns, in the block of memory specified by the hotSpots parameter, a list of IDs of all the hot spots in the QuickTime VR movie specified by the qtvr parameter that are currently visible. QTVRGetVisibleHotSpots also returns, as its function result, the number of hot spot IDs returned though the hotSpots parameter.
The handle specified by the hotSpots parameter must be a valid handle created by the Memory Manager.
You can use the QTVRGetHotSpotRegion function to get the region occupied by a hot spot.
OSErr QTVRGetHotSpotRegion (
QTVRInstance qtvr,
UInt32 hotSpotID,
RgnHandlehotSpotRegion);
The QTVRGetHotSpotRegion function returns, in the hotSpotRegion parameter, a handle to the region occupied by the hot spot, in the QuickTime VR movie specified by the qtvr parameter, whose ID is specified by the hotSpotID parameter. The region is clipped to the bounds of the movie's graphics world.
You can obtain the regions of all visible hot spots by calling the QTVRGetVisibleHotSpots function and then calling QTVRGetHotSpotRegion for each hot spot ID in the list.
The first time you call QTVRGetHotSpotRegion , a significant amount of memory might need to be allocated. Accordingly, you should always check for Memory Manager errors returned by QTVRGetHotSpotRegion .
Your application is responsible for disposing of the memory occupied by the returned region.
| Previous | Chapter Contents | Chapter Top | Next |